Document a pre-commit hook that commits the graph with the code that changed it by andrebrait · Pull Request #39 · Graphify-Labs/docs

andrebrait · 2026-10-18T05:04:07Z

What this adds

A new section in Share context with your team (guides/team-workflows.mdx), plus a pointer from step 4 of the repository workflow. It describes another way for teams to keep a committed graphify-out/graph.json current.

graphify hook install rebuilds the graph after each commit, in the background. When a team commits graph.json, each commit therefore leaves the rebuilt graph behind as an uncommitted change, and someone has to commit it separately. The alternative is a short pre-commit hook that rebuilds the graph before the commit and stages it. Each commit then carries the graph of its own code. The section covers:

tracking only graph.json (graphify-out/* + !graphify-out/graph.json), and how to move an existing setup that tracks all of graphify-out/;
.gitattributes: merge=graphify linguist-generated=true -diff, with what each attribute does;
the compact one-line graph.json written since 0.9.86 (fix: write graph.json as one line of compact JSON (#3413) graphify#4319), which GitHub counts as +1 −1 per rebuild;
registering the union merge driver without hook install, and how to recover a clone that skipped it;
the hook block, added to the pre-commit file in git's hooks directory (where graphify hook install puts its post-commit hook) or to a hook manager's pre-commit step, without disabling other checks; and, as an option, committing it in .githooks/ with core.hooksPath to share it;
the limits: skip switches, partial commits, commits git makes without running pre-commit (merges it completes, rebase, cherry-pick, revert), matching graphify releases, and commit latency.

Where it comes from

pfBlockerNG/pfBlockerNG runs this setup: a pre-commit hook rebuilds and stages graph.json, and the same .gitattributes line applies. Its recent merged PRs show graphify-out/graph.json as +1 −1 on GitHub.

Verification

I ran every snippet on the page verbatim in scratch repositories, with git 2.47.3 and graphify 0.9.92:

A commit that changes code includes the rebuilt graph.json and leaves a clean tree. A commit that stages only the graph does not rebuild it.
GRAPHIFY_SKIP_HOOK=1 skips the rebuild. Without graphify on PATH, the commit fails.
git merge --no-commit followed by git commit produces a graph identical to a fresh graphify update .. A merge that git completes without conflicts runs no pre-commit, and neither does a rebase. A pre-merge-commit hook's git add does not reach the merge commit either, so the page doesn't suggest one.
Without the merge driver, a merge that changes the graph on both sides conflicts in graph.json. The documented rm … && graphify update . && git add … recovery commits a fresh graph.
graphify update . took 49–58 s on a 2,832-file repository.

An independent review re-ran the snippets and also probed the stash, git commit <path>, cherry-pick/revert, patch, existing-hook (set -eu, final exit) and no-graph-repo cases. The page reflects its corrections.

graphify-labs

Graphify reviewed this change.

No issues found by static checks — no coupling regressions or blocking issues in the code graph. That is not the same as safe to merge: see what was not checked.

Not checked: tests were not run; no formal proof of the changed code.

Graphify review — findings

Adds a "Commit the graph with the code that changed it" section to the team workflows guide, with a committed .githooks/pre-commit script that rebuilds graph.json and stages it, so each commit carries the graph of its own code instead of leaving the post-commit rebuild as a dirty change. Setup tracks only graphify-out/graph.json through a narrowed .gitignore, marks it generated in .gitattributes, and registers the graphify union merge driver by hand, since that driver is only installed by graphify hook install. The hook fails the commit if the rebuild fails or graphify is missing, and GRAPHIFY_SKIP_HOOK=1 or --no-verify skips it at the cost of a stale graph. The partial-commit recipe built on git stash --keep-index --include-untracked is the part most likely to leave a reader's working tree in a bad state, because it never says how to restore the stash afterward.

No blocking issues surfaced. 2 lower-confidence candidates did not survive cross-model review.

Analysis details — impact, health, verification

Impact & health

Graphify review

Impact — 6 functions depend on the 6 functions this change touches.

Health — grade A; no new coupling hotspots.

Verification — 6 functions in the blast radius were not formally verified this run (proofs are advisory here).

Gate & verification

graphify gate

PASS — objectively clean (no health regressions, tests not run — proofs not run this pass (advisory)). Grounded, not self-assessed.

Advisory (not blocking):

verification_scope: 6 function(s) in the blast radius were not formally verified this run

Test selection

0 test file(s) selected via static blast radius.

Escalated to a full run for safety — the selection is not trustworthy on its own (see below). CI should run the whole suite.

non-code file(s) changed (guides/team-workflows.mdx) → running the full suite for safety (a code graph can't see config/fixture/data deps)

changed code file(s) with no mapped test (guides/team-workflows.mdx) — a coverage gap or a missing link — running the full suite rather than only the selected tests

Selection is safe under the controlled-regression assumption; always-run tests + a periodic full run are the backstops. Advisory — it never changes the check verdict.

SyedFahad7 · 2026-10-22T04:21:58Z

Helpful section, and the commands exist. Two things in the snippet will surprise people who already use graphify hook install.

Pin PYTHONHASHSEED=0 in the hook, the way graphify hook install does. Clustering walks string-keyed sets whose order depends on that seed, so community ids change between runs. Without the pin, graph.json is rewritten on commits that did not change the structure.
The merge-driver line graphify merge-driver %O %A %B only works when graphify is on PATH. hook install writes "<pinned python>" -m graphify merge-driver %O %A %B for that reason (GUI git, and Windows paths that contain a space). Please say to use that pinned form, or to copy merge.graphify.driver from a repo where graphify hook install has already registered it.

One sentence worth adding: this replaces both hooks graphify hook install adds, post-commit and post-checkout. After a branch switch, run graphify update .. Step 5 already says to do that after pulls and merges.

Checked against the package: graphify update . is the code-only rebuild (no API key). graphify merge-driver union-merges nodes and edges, so a deleted symbol can survive a merge, which the page already says. Current graph.json is one compact line. The .gitattributes flags linguist-generated and -diff are extra on top of the merge=graphify line hook install writes, and they are fine to keep.

…changed it

…replaces

mintlify · 2026-10-22T04:24:22Z

✅ Preview approved

@SyedFahad7 approved a Mintlify preview for commit ff12bbf.

andrebrait · 2026-10-22T04:24:32Z

Thanks, all three are in (ff12bbf, rebased on current main).

The hook now runs PYTHONHASHSEED=0 graphify update ., with a sentence on why. Since 0.9.66 graphify update also sets the seed itself when you don't, so a bare update is already deterministic on current releases. The explicit pin matches hook install and also covers older releases.
The merge-driver step now says to copy merge.graphify.driver from a repository where graphify hook install registered it, or to use the pinned form '"/path/to/python" -m graphify merge-driver %O %A %B'. It shows how to find that Python on Linux and macOS, and notes that the quotes matter for Windows paths with spaces. I checked it: a merge where both branches changed graph.json resolved with graphify off PATH, and the merged graph contained both sides' symbols.
The page now says this hook replaces all four hooks hook install adds (post-commit, post-checkout, post-merge, post-rewrite). After a branch switch, run graphify update . to refresh the untracked graphify-out/ files. The committed graph already matches each commit.

andrebrait · 2026-10-26T11:45:02Z

@SyedFahad7 could you take another look? All three points are addressed in ff12bbf (details in my previous comment), and CI is green. The Mintlify preview still needs a maintainer to approve it, since the PR comes from a fork.

mintlify · 2026-10-26T11:48:37Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
graphify-labs-inc	🟢 Ready	View Preview	Oct 26, 2026, 11:48 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

SyedFahad7

Looks good. Your three fixes are in (PYTHONHASHSEED pin, pinned merge-driver Python, and which hooks this replaces). Preview builds cleanly on the team-workflows page.

This sits next to our Cloud move guide without conflict: yours is the local path for teams that commit graph.json; ours is for people switching assistants to the hosted MCP.

SyedFahad7 · 2026-10-26T12:27:31Z

Quick note on the Guides sidebar (not from your change — this is existing docs.json):

Mintlify currently has a Team group with guides/team-workflows as the root and only guides/pull-requests as a child. So the sidebar shows Team as the expandable label, and the only nested item is Review pull requests with graph context. People never see the real title of the root page (Share context with your team) in that list.

We're flattening that nav in a follow-up so both pages show as peers under Guides (no root hiding the team-workflows title). Your pre-commit section content is fine as approved.

graphify-labs Bot reviewed Oct 18, 2026

View reviewed changes

andrebrait force-pushed the guides/pre-commit-graph branch 2 times, most recently from 6b7fcfa to 69e84ee Compare October 18, 2026 05:50

andrebrait added 2 commits October 22, 2026 04:24

Document a pre-commit hook that commits the graph with the code that …

0af769e

…changed it

Pin PYTHONHASHSEED and the merge-driver Python; say which hooks this …

ff12bbf

…replaces

andrebrait force-pushed the guides/pre-commit-graph branch from 69e84ee to ff12bbf Compare October 22, 2026 04:24

mintlify Bot deployed to staging October 26, 2026 11:48

View deployment

SyedFahad7 approved these changes Oct 26, 2026

View reviewed changes

SyedFahad7 merged commit df09c6c into Graphify-Labs:main Oct 26, 2026
3 checks passed

andrebrait deleted the guides/pre-commit-graph branch October 26, 2026 12:49

SyedFahad7 mentioned this pull request Oct 26, 2026

Restore Contributors to Release Notes #54

Merged

Navigation Menu

Repository navigation

Document a pre-commit hook that commits the graph with the code that changed it - #39

Document a pre-commit hook that commits the graph with the code that changed it#39
SyedFahad7 merged 2 commits into
Graphify-Labs:mainfrom
pfBlockerNG:guides/pre-commit-graph

andrebrait commented Oct 18, 2026 •

edited

Loading

Uh oh!

graphify-labs Bot left a comment

Uh oh!

SyedFahad7 commented Oct 22, 2026

Uh oh!

mintlify Bot commented Oct 22, 2026 •

edited

Loading

Uh oh!

andrebrait commented Oct 22, 2026

Uh oh!

andrebrait commented Oct 26, 2026

Uh oh!

mintlify Bot commented Oct 26, 2026 •

edited

Loading

Uh oh!

SyedFahad7 left a comment

Uh oh!

SyedFahad7 commented Oct 26, 2026

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

andrebrait commented Oct 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this adds

Where it comes from

Verification

Uh oh!

graphify-labs Bot left a comment

Choose a reason for hiding this comment

Graphify review — findings

Impact & health

Graphify review

Gate & verification

graphify gate

Test selection

Test selection

Uh oh!

SyedFahad7 commented Oct 22, 2026

Uh oh!

mintlify Bot commented Oct 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Preview approved

Uh oh!

andrebrait commented Oct 22, 2026

Uh oh!

andrebrait commented Oct 26, 2026

Uh oh!

mintlify Bot commented Oct 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SyedFahad7 left a comment

Choose a reason for hiding this comment

Uh oh!

SyedFahad7 commented Oct 26, 2026

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

andrebrait commented Oct 18, 2026 •

edited

Loading

mintlify Bot commented Oct 22, 2026 •

edited

Loading

mintlify Bot commented Oct 26, 2026 •

edited

Loading